canon(constraint): A Link Is a Tap, Not a String — deliver actionable…#256
Conversation
… output in actionable form New tier-1 constraint born from the 2026-06-14 bee-ai-auth-mcp debrief: actionable outputs (links, commands, paths) must be delivered in their lowest-friction actionable form for the operator's surface; the requested artifact must never be displaced by process narration. Smell tests, failure modes, MUST-rules, exclusions. epoch/tier/stability set provisionally — operator to confirm on review.
Canon Quality —
|
| Line | Rule | Occurrence | Message |
|---|---|---|---|
| 242 | dead-reference |
klappy://writings/nothing-new-even-ai |
URI does not resolve |
writings/choosing-faith-not-fear.md — 1 finding(s)
| Line | Rule | Occurrence | Message |
|---|---|---|---|
| 203 | dead-reference |
klappy://writings/four-questions-that-change-everything |
URI does not resolve |
writings/getting-started-with-odd-and-oddkit.md — 4 finding(s)
| Line | Rule | Occurrence | Message |
|---|---|---|---|
| 69 | legacy-link-pattern |
/page/writings/the-journey-from-ai-tasks-to-ai-augmented-workflows |
Use a klappy:// URI instead of /page/ path |
| 202 | legacy-link-pattern |
/page/docs/oddkit/proactive/proactive-bootstrap |
Use a klappy:// URI instead of /page/ path |
| 204 | legacy-link-pattern |
/page/docs/examples/project-instructions-template |
Use a klappy:// URI instead of /page/ path |
| 260 | legacy-link-pattern |
/page/writings/the-journey-from-ai-tasks-to-ai-augmented-workflows |
Use a klappy:// URI instead of /page/ path |
writings/the-broken-wall-and-the-buried-talent.md — 1 finding(s)
| Line | Rule | Occurrence | Message |
|---|---|---|---|
| 332 | dead-reference |
klappy://draft-zeros/appendix-a-the-biblical-roots |
URI does not resolve |
writings/the-voice-came-first.md — 1 finding(s)
| Line | Rule | Occurrence | Message |
|---|---|---|---|
| 244 | dead-reference |
klappy://writings/four-questions-that-change-everything |
URI does not resolve |
Soft-block mode — this status is informational; the job will not fail. Hard-block ships in PR-3.2 after the observation cycle.
What to do for each finding:
- Fix the slug if the target now lives at a different
klappy://URI.- Remove the link if it is no longer needed.
- Allowlist with a reason if the rot is intentional (e.g. forward-ref to an upcoming article): place
<!-- audit-allow: dead-reference reason="..." -->on the line above the offending link. The directive is line-level and scopes to the next markdown link.
Spec: klappy://docs/oddkit/specs/oddkit-audit · Workflow: .github/workflows/canon-quality.yml · Run: #282
Canon Quality — P0010 Retrieval-Readiness
|
Canon Quality — Homepage Surfacing ✅48 essay(s) scanned. Soft report — never blocks; the hard field gate is the Frontmatter Schema job. All published essays resolve to the homepage feed. Report: |
Canon Quality — Frontmatter Schema ✅All 48 file(s) in Validator: |
1 participant
… output in actionable form
New tier-1 constraint born from the 2026-06-14 bee-ai-auth-mcp debrief: actionable outputs (links, commands, paths) must be delivered in their lowest-friction actionable form for the operator's surface; the requested artifact must never be displaced by process narration. Smell tests, failure modes, MUST-rules, exclusions.
epoch/tier/stability set provisionally — operator to confirm on review.
Note
Low Risk
Documentation-only canon addition with no runtime or auth changes; only affects agent behavior guidance once adopted.
Overview
Introduces
canon/constraints/actionable-output-in-actionable-form.md— a new tier-1,semi_stableconstraint that governs how agents deliver anything the operator will act on (links, commands, paths, addresses).The doc frames undelivered actionable output as debt (parallel to “a claim is a debt”) and requires lowest-friction form for the current surface, with mobile as the default (e.g. markdown links instead of raw URLs in prose, copy-ready code blocks for shell). It defines smell tests and failure modes (raw URL in prose, process-as-substitute, surface-blindness, repeat-deafness), five MUST rules (lead with the artifact, change form on repeat requests), and exclusions (raw value when requested, no actionable surface, safety over one-tap for secrets).
Frontmatter links it to
magical-first-run, the model operating contract, and axioms; it complementsrelease-validation-gate. Origin is documented as a 2026-06-14bee-ai-auth-mcpdebrief (iOS operator repeatedly asked for a tappable link). Epoch E0008.5 is marked provisional for operator confirmation on review.Reviewed by Cursor Bugbot for commit e18128a. Bugbot is set up for automated code reviews on this repo. Configure here.